"""Python版本兼容性适配层

此模块提供了跨Python版本的兼容性支持，主要包括：
1. 类型注解兼容性
2. 标准库API兼容性
3. 特性检测和版本适配
4. 常用功能的兼容性包装
"""

import sys
import json
import datetime
import functools
import contextlib
from typing import (
    Any, Dict, List, Union, Optional, 
    Callable, TypeVar, Iterator,
    Awaitable
)
from datetime import timezone
from pathlib import Path

# 类型变量
T = TypeVar('T')
K = TypeVar('K')
V = TypeVar('V')

# Python版本检测
PY37 = sys.version_info >= (3, 7)
PY38 = sys.version_info >= (3, 8)
PY39 = sys.version_info >= (3, 9)
PY310 = sys.version_info >= (3, 10)
PY311 = sys.version_info >= (3, 11)

# 类型注解兼容性
if PY38:
    from typing import Literal, Protocol, TypedDict, Final
else:
    from typing_extensions import Literal, Protocol, TypedDict, Final

# 时间处理兼容性
def get_utc_now() -> datetime.datetime:
    """获取UTC时间的兼容性函数"""
    if PY311:
        return datetime.datetime.now(datetime.UTC)
    return datetime.datetime.now(timezone.utc)

def format_iso_datetime(dt: datetime.datetime) -> str:
    """格式化日期时间为ISO 8601格式的兼容性函数"""
    if PY39:
        return dt.replace(tzinfo=None).isoformat(timespec="seconds")
    return dt.replace(tzinfo=None).strftime("%Y-%m-%dT%H:%M:%S")

# 数据类兼容性
if PY37:
    from dataclasses import dataclass, field, asdict, astuple
else:
    from typing_extensions import dataclass
    from dataclasses import field, asdict, astuple

# 函数式编程兼容性
def compose(*functions: Callable) -> Callable:
    """函数组合的兼容性函数"""
    def compose_two(f: Callable, g: Callable) -> Callable:
        return lambda x: f(g(x))
    return functools.reduce(compose_two, functions, lambda x: x)

# 集合操作兼容性
def dict_union(d1: Dict[K, V], d2: Dict[K, V]) -> Dict[K, V]:
    """字典合并的兼容性函数"""
    if PY39:
        return d1 | d2
    return {**d1, **d2}

# 上下文管理兼容性
@contextlib.contextmanager
def nullcontext(enter_result: T = None) -> Iterator[T]:
    """空上下文管理器的兼容性函数"""
    yield enter_result

# 文件操作兼容性
def path_is_relative_to(path: Path, other: Union[str, Path]) -> bool:
    """路径关系检查的兼容性函数"""
    if PY39:
        return path.is_relative_to(other)
    try:
        path.relative_to(other)
        return True
    except ValueError:
        return False

# 字符串操作兼容性
def str_removeprefix(text: str, prefix: str) -> str:
    """字符串前缀移除的兼容性函数"""
    if PY39:
        return text.removeprefix(prefix)
    return text[len(prefix):] if text.startswith(prefix) else text

def str_removesuffix(text: str, suffix: str) -> str:
    """字符串后缀移除的兼容性函数"""
    if PY39:
        return text.removesuffix(suffix)
    return text[:-len(suffix)] if text.endswith(suffix) else text

# 类型检查兼容性
def is_generic_type(tp: Any) -> bool:
    """泛型类型检查的兼容性函数"""
    if PY310:
        from typing import _GenericAlias  # type: ignore
        return isinstance(tp, _GenericAlias)
    else:
        from typing import _GenericAlias  # type: ignore
        return isinstance(tp, _GenericAlias)

# 异常处理兼容性
try:
    from json.decoder import JSONDecodeError
except ImportError:
    JSONDecodeError = ValueError  # type: ignore

# 常用类型别名
JsonDict = Dict[str, Any]
JsonList = List[Any]
OptionalStr = Optional[str]
OptionalInt = Optional[int]
PathLike = Union[str, Path]
AnyCallable = Callable[..., Any]
AsyncFunction = Callable[..., Awaitable[Any]]

# 常用装饰器
def deprecated(func: AnyCallable) -> AnyCallable:
    """废弃警告装饰器"""
    @functools.wraps(func)
    def wrapper(*args: Any, **kwargs: Any) -> Any:
        import warnings
        warnings.warn(f"{func.__name__} is deprecated", DeprecationWarning, stacklevel=2)
        return func(*args, **kwargs)
    return wrapper

# 导出所有公共API
__all__ = [
    # 版本检测
    'PY37', 'PY38', 'PY39', 'PY310', 'PY311',
    
    # 类型注解
    'Literal', 'Protocol', 'TypedDict', 'Final',
    
    # 时间处理
    'get_utc_now', 'format_iso_datetime',
    
    # 数据类
    'dataclass', 'field', 'asdict', 'astuple',
    
    # 函数式编程
    'compose',
    
    # 集合操作
    'dict_union',
    
    # 上下文管理
    'nullcontext',
    
    # 文件操作
    'path_is_relative_to',
    
    # 字符串操作
    'str_removeprefix', 'str_removesuffix',
    
    # 类型检查
    'is_generic_type',
    
    # 异常处理
    'JSONDecodeError',
    
    # 类型别名
    'JsonDict', 'JsonList', 'OptionalStr', 'OptionalInt', 'PathLike',
    'AnyCallable', 'AsyncFunction',
    
    # 装饰器
    'deprecated',
]
